4.6 Link abbreviations

Long URLs can be cumbersome to type, and often many similar links are needed in a document. For this you can use link abbreviations. An abbreviated link looks like this

[[linkword:tag][description]]

where the tag is optional. The linkword must be a word, starting with a letter, followed by letters, numbers, ‘-’, and ‘_’. Abbreviations are resolved according to the information in the variable org-link-abbrev-alist that relates the linkwords to replacement text. Here is an example:

(setq org-link-abbrev-alist
  '(("bugzilla"  . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
    ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
    ("google"    . "http://www.google.com/search?q=")
    ("gmap"      . "http://maps.google.com/maps?q=%s")
    ("omap"      . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
    ("ads"       . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))

If the replacement text contains the string ‘%s’, it will be replaced with the tag. Using ‘%h’ instead of ‘%s’ will url-encode the tag (see the example above, where we need to encode the URL parameter.) Using ‘%(my-function)’ will pass the tag to a custom function, and replace it by the resulting string.

If the replacement text don’t contain any specifier, it will simply be appended to the string in order to create the link.

Instead of a string, you may also specify a function that will be called with the tag as the only argument to create the link.

With the above setting, you could link to a specific bug with [[bugzilla:129]], search the web for ‘OrgMode’ with [[google:OrgMode]], show the map location of the Free Software Foundation [[gmap:51 Franklin Street, Boston]] or of Carsten office [[omap:Science Park 904, Amsterdam, The Netherlands]] and find out what the Org author is doing besides Emacs hacking with [[ads:Dominik,C]].

If you need special abbreviations just for a single Org buffer, you can define them in the file with

#+LINK: bugzilla  http://10.1.2.9/bugzilla/show_bug.cgi?id=
#+LINK: google    http://www.google.com/search?q=%s

In-buffer completion (see Completion) can be used after ‘[’ to complete link abbreviations. You may also define a function org-PREFIX-complete-link that implements special (e.g., completion) support for inserting such a link with C-c C-l. Such a function should not accept any arguments, and return the full link with prefix.